<!DOCTYPE HTML>
<html>
<head>
<title>Iscas85sim - Read Me</title>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
</head>
<body>
<h1>Iscas85sim - Read Me</h1>

Iscas85sim - An Iscas 85 Circuit Compiler/Simulator

<h2>Authors</h2>
<ul>
	<li><a href="mailto:ei09090@fe.up.pt">Clara Sacramento</a></li>
	<li><a href="mailto:ei09086@fe.up.pt">Diogo Teixeira</a></li>
	<li><a href="mailto:ei09008@fe.up.pt">João Costa</a></li>
	<li><a href="mailto:ei09055@fe.up.pt">Pedro Dias</a></li>
</ul>

<h2>Description</h2>
<p>
Iscas85sim is a compiler/simulator for the Iscas 85 Netlist files. 
It is able to either simulate the circuit behaviour given an input or generate a dotty file of the circuit (with or without the simulation result).
</p>

<h2>Usage</h2>
<pre>
    iscas85sim [options ...] &lt;netlist_file&gt;

    Options: 
        -d, --dotty &lt;output_file&gt;     Outputs a dotty representation of the
                                      circuit
        -h, --help                    Prints help information
        -s, --simulate &lt;input_file&gt;   Simulates the circuit
        -o, --output &lt;output_file&gt;    Outputs the results of the simulation
                                      to a file (default file: result.out)
        -v, --values                  Outputs a dotty representation of the
                                      circuit with the simulation results
        -g, --generate &lt;input_file&gt;   Generates a sample input file for the
                                      circuit (default file: input.in)
</pre>

<h3>Input File Syntax</h3>
<ul>
	<li><strong>Comments:</strong> Started with '#'</li>
	<li><strong>First Line (excluding comments and blank lines):</strong> &lt;error&gt;:&lt;fill&gt;
		<ul>
			<li><strong>&lt;error&gt;:</strong> "stuck at" error probability (decimal value between 0.0 and 1.0)</li>
			<li><strong>&lt;fill&gt;:</strong> default value for undefined nodes (f0 or f1 for 0 or 1)</li>
		</ul>
	</li>
	<li><strong>Other lines:</strong> &lt;node&gt;:&lt;value&gt;
		<ul>
			<li><strong>&lt;node&gt;:</strong> '*' or node name ('*' represents the first input node with no value)</li>
			<li><strong>&lt;value&gt;:</strong> 0 or 1</li>
		</ul>
	</li>

	<li><strong>Value assignment priority:</strong> &lt;node&gt; >> '*' >> &lt;fill&gt;</li>
</ul>

<h2>Examples</h2>
(This examples can be run from the "examples" folder)
<ul>
	<li><strong>Example 1</strong>
		<ul>
			<li><strong>Description:</strong> Increments the binary value 011</li>
			<li><strong>Expected output:</strong> 0100 (output1.out)</li>
			<li><strong>Command:</strong> <code>java -jar ../iscas85sim.jar 3bitinc.isc -s input1.in -o output1.out</code></li>
		</ul>
	</li>
	<li><strong>Example 2</strong>
		<ul>
			<li><strong>Description:</strong> Increments the binary value 111 (overflow)</li>
			<li><strong>Expected output:</strong> 1000 (output2.out)</li>
			<li><strong>Command:</strong> <code>java -jar ../iscas85sim.jar 3bitinc.isc -s input2.in -o output2.out</code></li>
		</ul>
	</li>
	<li><strong>Example 3</strong>
		<ul>
			<li><strong>Description:</strong> Generate the dotty file representing a 3-bit incrementor</li>
			<li><strong>Expected output:</strong> The dotty file (dotty3.dot)</li>
			<li><strong>Command:</strong> <code>java -jar ../iscas85sim.jar 3bitinc.isc -d dotty3.dot</code></li>
		</ul>
	</li>
	<li><strong>Example 4</strong>
		<ul>
			<li><strong>Description:</strong> Generate the same dotty file as example 3, but with the simulation results of example 2</li>
			<li><strong>Expected output:</strong> The dotty file with the results (dotty4.dot)</li>
			<li><strong>Command:</strong> <code>java -jar ../iscas85sim.jar 3bitinc.isc -s input2.in -d dotty4.dot -v</code></li>
		</ul>
	</li>
	<li><strong>Example 5</strong>
		<ul>
			<li><strong>Description:</strong> Simulates a circuit with errors</li>
			<li><strong>Expected output:</strong> Unpredictable result (output5.out)</li>
			<li><strong>Command:</strong> <code>java -jar ../iscas85sim.jar 3bitinc.isc -s input5.in -o output5.out</code></li>
		</ul>
	</li>
</ul>

<h2>Known Problems/Restictions</h2>
<ul>
	<li>It's not possible to assign different error probability for different nodes</li>
	<li>The simulation doesn't support undefined values (if a node has an undefined value, it's assumed the fill value as the node's value)</li>
	<li>Each execution only allows one simmulation (it's not possible to execute chain-reactions without manually editing the input file)</li>
</ul>
</body>
</html>
